Fixes #3316.

Changelog Entry

Added

• Resolves #3316. Refactored platform-neutral APIs into the new api package, to be reused on React Native component, in PR #3543 by @compulim
  • The new layering is core -> api -> component (HTML-only) -> bundle
  • Includes composition mode, platform-neutral React hooks, and localization resources
  • Most hooks are available in the new api package. Some hooks are only available on the existing component package, due to their platform dependency or coupling with visual components. For example, Web Worker, 2D canvas, useMicrophoneButton* are not available on the api package
  • Most implementation of middleware are only available on component package due to their coupling with visual components or platform features. Some implementations, such as, card action middleware and activity grouping middleware, are available on api package. For example:
    • Carousel layout and stacked layout is only available on component package due to their coupling with their respective visual components
    • For card action middleware, imBack, messageBack and postBack actions are available on api package, but call, openUrl and other platform-dependent actions are only available on component package
  • activityMiddleware, attachmentMiddleware, etc, now support array for multiple middleware

Description

This is for refactoring platform-neutral APIs into a new api package, to be reused on React Native component.

Design

Please see #3316 for design.

In general, platform-neutral code are being moved to api package. Code that left on the component package assumes it is running inside a web browser.

We also improved error handling, because <ErrorBox> is a visual component and is platform-dependent. We need to update the error boundary component and render <ErrorBox> differently on different platforms.

Although both React and React Native should support styleSet, the content could be fundamentally different. Thus, styleSet are not offered in api packages, but in component and the future native-component package.

Specific Changes

• Added new api package, layered between core and component
  • Moved most React hooks to the new api package
  • Moved localization resources to the new api package
  • Moved composition mode to the new api package
• Split part of card action middleware into api package, while keeping some in the component package
  • imBack, messageBack, and postBack, which are platform-neutral, are moved to api package
  • call, openUrl, and others, are left untouched in the component package
• Moved grouping activity middleware into api package
• Improved error handling
  • Added new UserlandBoundary to add error boundary to user components (e.g. components rendered via middleware)
  • Added internalErrorBoxClass prop for internal use
    • Users of api package can pass their own React component (e.g. component package running in development mode)
    • api will render <ErrorBox> when error caught in error boundary, which in turn, will use the internalErrorBoxClass to render
  • When running in non-development mode (node_env !== 'development), component will pass undefined to internalErrorBoxClass and will hide the <ErrorBox>

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)